docs(plugin-charts): mark normalizeSeries' chartType limb internal-only and pin the split - #7815

Fixes #7744

Option B of the card's three-way disposition, per the PM ruling on the claim comment: the
chartType limb is annotated as internal-only and the split is pinned. Not A (leave the two
faces disagreeing with nothing written down), and not C — retiring the limb at the reader
would change what the internal producers render, which is a reader-side decision of its own.

No behaviour changes. normalizeSeries returns byte-identical output for the same input;
the diff is a docblock, a two-line comment beside the limb, one new test file, and an
empty-frontmatter changeset. ChartRenderer.tsx and packages/types/ are untouched.

What the split is

normalizeSeries resolves the per-series family as str(raw.chartType) ?? str(raw.type) — the
internal spelling first. That limb is correct: chartType is the carrier of the renderer's
internal dataKey series shape. ChartRenderer's series? prop is a union of exactly the two
shapes, and it declares chartType? on the dataKey arm and on no other — the authored arm
carries type? instead. DashboardRenderer, ObjectView and the dataset path write that arm.

But the one function normalizes both shapes, and by the time raw arrives it is a bag of keys
with nothing on it naming its producer. So an author who skips validation still gets chartType
honoured at runtime — over the declared type, read second — while the authoring face refuses
that same key by name. Two faces, one disagreement, and until now nothing anywhere said so.

1. The annotation, and the refusal it delegates to

The normalizeSeries docblock now names which face owns which spelling, records that the limb is
lit (and that a green ablation on it is not a licence to delete it), and states that the split is
deliberate and pinned.

It delegates rather than summarises: the refusal is named as
ChartDataSeriesSchema.chartType in packages/types/src/zod/data-display.zod.ts
(objectui#7694 / PR #7737), together with its existing pin
packages/types/src/__tests__/chart-series-chart-type-alias-refusal-7694.test.ts. The rule, its
message and its remedy are not copied into plugin-charts — per objectui#7765's landing record,
a one-line summary in a second file rots, because only one of the two files is ever edited.

2. The pin, and why this shape catches drift

packages/plugin-charts/src/__tests__/chartType-internal-only-7744.test.ts.

The refusal already had a pin, and the reader already had pins. Neither file pinned the pair —
which is exactly how the split survived to be found in the contract review of PR #7737. What this
case pins is the relationship: the key the validator refuses is the key the reader prefers.

Shape choices that make it catch drift rather than describe it:

• One fixture, read by every assertion — { name: 'margin', type: 'area', chartType: 'line' } —
  so the two faces are measured against the same input, not against two fixtures free to drift.
• Both spellings written, with different values. This is what makes the reader's precedence
  observable at all. With only chartType written, a reordered reader returns the identical answer
  and a pin on the value alone stays green straight through the change it exists to catch.
• The refusal side asserts the issue paths equal exactly ['chartType'] — so the fixture being
  refused for some other reason fails too, rather than passing as a phantom. An accept-control on
  the same document with the key dropped is the other half of that.
• Nothing loose. No assertion is written as "chartType is honoured somehow"; each one fails
  under exactly one of the two behaviours, and the messages name objectui#7744 and say which side
  moved ("area" means REORDERED, undefined means DELETED).
• A compile-time half over ChartRenderer's series? union arms pins the same split in
  TypeScript. Confirmed compiled, not phantom: tsc -p tsconfig.test.json --listFiles resolves the
  file (1 hit, not 0).

3. Proof of no behaviour change (same input, same output)

A probe imports the module and runs 336 input cases through normalizeChartSchema — the only
public entry into normalizeSeries — plus comboBaseFamily, effectiveChartFamily,
formatterFor, ticksFor, domainFor and the exported sets. 288 of those cases are the
chartType/type limb exhaustively: every combination of present/absent across 12 values per
spelling, including disagreeing pairs, empty strings, wrong-typed values, and the same matrix again
reached through categories.

before (blob 05a66dfb…)  sha256 1681dfd534b7f01f798bc9fef45368abba0051bc136c67e3b7cd0c410c7fd896
after  (blob 0a2b702c…)  sha256 1681dfd534b7f01f798bc9fef45368abba0051bc136c67e3b7cd0c410c7fd896
=> byte-identical

The pre-edit blob is 05a66dfb5b9c9a322761e1e1a694ac7a57af1e54 — the same blob the card names at
both ends of PR #7737, so this is measured against exactly the reader the reviewer measured.

The probe was itself shown sensitive, otherwise "identical" would be vacuous: reordering the
limb in a scratch copy (never in the repo) moves 49 of the 336 cases, e.g.
{ name: 'margin', chartType: 'bar', type: 'line' } goes from chartType: 'bar' to 'line'.

The stronger reading agrees: the package's pre-existing suite was 45 files / 410 tests, all
passing before the edit and 46 files / 416 tests, all passing after — the delta is exactly
this PR's one new file and its six cases; no pre-existing test changed verdict.

4. Lit controls — the pin goes red from either side, and names it

Both mutations ran under trap … EXIT INT TERM with absolute paths, the mutation confirmed on disk
by anchored text counts and a changed blob hash before anything was read (an empty hash reads as
failure), and restoration proved by blob-hash equality plus an empty git diff HEAD — state,
not whether the trap fired. Both were run after the implementation was committed, so HEAD is
the correct restore reference.

The relationship case is red in both directions; the side-specific cases name which face
moved. Sample diagnostic, verbatim from the reader mutation:

AssertionError: objectui#7744: `normalizeSeries` no longer resolves the per-series family from
`chartType` first. `"area"` here means the limb was REORDERED; `undefined` means it was DELETED.
Either one changes what the internal `dataKey`-shape producers render (DashboardRenderer /
ObjectView / the dataset path) — that is a reader-side decision, not a doc fix.
expected 'area' to be 'line'

Restoration, both controls:

reader    HEAD blob 0a2b702c…  mutated 1f53c339…  post 0a2b702c…  git diff HEAD: empty
authoring HEAD blob 1cbacf06…  mutated ae8318b0…  post 1cbacf06…  git diff HEAD: empty
whole tree afterwards: git status --short empty; the pin re-runs 6 passed, exit 0

5. Verification

Union run after the final commit, at 1120ee392, uncached (--force), through turbo:

Derived gate family for the changed paths (.changeset/*.md, packages/plugin-charts/src/**), all
exit 0: check-control-bytes · check-changeset-no-major · check-changeset-overwrite ·
check-changeset-fixed · check-lint-coverage · check-type-check-coverage ·
check-unreferenced-sources. Also self-scanned for control bytes beyond the gate
(grep -naP over both touched files, no hits).

Declared narrowing: the repo-wide pnpm lint was not run locally; eslint was run on the
affected package only. Evidence the narrowing excludes nothing: the population is read from
eslint's own config, not guessed (57 files resolved in this package, from --format json); this
repo has no type-aware linting configured (no projectService / parserOptions.project in
eslint.config.*), so a comment-only edit cannot move any untouched file's verdict. CI runs the
full farm regardless.

6. Changeset gate — verdict verbatim

node scripts/check-changeset-presence.mjs, exit 0:

Compared the working tree with a617bb8d3 (merge-base with origin/main): 3 file(s) changed, 2 of
them published source of a package the release covers, 0 of them a manifest whose published
contract moved, 0 under a package changesets ignores, 1 changeset(s) added.
✅  2 source file(s) of 1 released package(s) changed, and this change declares 1 changeset(s):
.changeset/7744-chart-type-internal-only.md.
    Every one of them has an EMPTY frontmatter — declared as releasing nothing, which
    is the explicit exemption and a complete answer to this gate.

The empty-frontmatter form is the honest one here: B ships no published behaviour. Never major.
No skip-changeset label was applied — in this repo that label reads nothing and exempts nothing;
the empty-frontmatter declaration is the mechanism, and the gate's verdict line is the authority.

Clause-② remains no

Nothing here makes normalizeSeries produce a different output for the same input — that is
measured above, not asserted. The limb is untouched (still 1 occurrence, unchanged);
ChartRenderer.tsx and packages/types/ carry no edit in this PR.

🤖 Generated with Claude Code

https://claude.ai/code/session_01KbJQ1y1J12nZxYzFWhP8Q3

Generated by Claude Code